<h2>Why is this an issue?</h2>
<p>With the introduction of Markdown support in Javadoc comments in Java 23, developers should prefer Markdown syntax over legacy HTML tags (e.g.,
<code>&lt;b&gt;</code>, <code>&lt;i&gt;</code>, <code>&lt;code&gt;</code>, <code>&lt;ul&gt;</code>, <code>&lt;li&gt;</code>, etc.) and legacy Javadoc
tags (e.g. <code>{@link java.util.HashMap}</code>, <code>{@code Object}</code>).</p>
<p>Mixing HTML and Markdown can lead to readability issues and inconsistencies in rendering across tools. Markdown is generally more readable, less
cluttered and, should be preferred over HTML tags when possible.</p>
<p>This rule will raise an issue when an HTML tag or a legacy Javadoc tag inside a markdown comment could be replaced with a slimmer, and more
cohesive, syntax.</p>
<h2>How to fix it</h2>
<p>Here is a list of tags that should be replaced with markdown syntax:</p>
<ul>
  <li> <code>&lt;p&gt;</code> should be replaced with 2 new lines </li>
  <li> <code>&lt;code&gt;MyCode&lt;/code&gt;</code>, <code>{@code MyCode}</code> should be replaced with <code>`MyCode`</code> </li>
  <li> <code>&lt;i&gt;italic text&lt;/i&gt;</code>, <code>&lt;em&gt;</code> should be replaced with <code>*italic text*</code> </li>
  <li> <code>&lt;b&gt;bold text&lt;/b&gt;</code>, <code>&lt;strong&gt;</code> should be replaced with <code>**bold text**</code> </li>
  <li> <code>&lt;ul&gt;&lt;li&gt;list item&lt;/li&gt;&lt;/ul&gt;</code>, <code>&lt;ol&gt;&lt;li&gt;</code> should be replaced with <code>* list
  item</code> </li>
  <li> <code>{@link some.java.Class}</code> should be replaced with <code>[some.java.Class]</code> </li>
  <li> <code>{@link #equals(Object) equals}</code> should be replaced with <code>[equals][#equals(Object)]</code> </li>
</ul>
<h3>Code examples</h3>
<h4>Noncompliant code example</h4>
<pre data-diff-id="1" data-diff-type="noncompliant">
/// This is a markdown Javadoc comment
/// &lt;b&gt;ExampleClass&lt;/b&gt; is a simple utility for &lt;i&gt;demonstration purposes&lt;/i&gt;.
/// &lt;p&gt;
///     Use &lt;code&gt;ExampleClass.run()&lt;/code&gt; to execute the example.
/// &lt;/p&gt;
/// {@link some.java.Class} for more details
public class ExampleClass {
}
</pre>
<h4>Compliant solution</h4>
<pre data-diff-id="1" data-diff-type="compliant">
/// This is a markdown Javadoc comment
/// **ExampleClass** is a simple utility for *demonstration purposes*.
///
/// Use `ExampleClass.run()` to execute the example.
/// [some.java.Class] for more details
public class ExampleClass {
}
</pre>
<h2>Resources</h2>
<h3>Documentation</h3>
<ul>
  <li> <a href="https://openjdk.org/jeps/467">JEP 467: Markdown Documentation Comments</a> </li>
</ul>

